v0.5 - 2008.01.20
  - First Release

--------------------------------------------------------------------------

The AllPlays Play-Tracking Framework has three major components:

  1. Play Tracking
  2. Database
  3. Synchronization

1. Play Tracking
================
The Play Tracking tools create XML files that record a timestamp for every
track played in iTunes or on an iPod.

The iTunes tool comes in the form of an iTunes Plug-In, AllPlays.dll.  
This, along with its configuration file, AllPlays.ini, must be placed in
the iTunes Plug-Ins directory.

AllPlays.ini contains two configuration options:
  1. xmlPath = <path, including filename, where XML data should be written>
  2. delay = <listening time, in seconds, before a track is counted as
              "played">
     If the track is shorter than 2 * delay, then it will be counted as
     "played" when 50% of the track is played.  If the track is paused or
     a section is skipped before "delay" is reached, the track will not be
     counted (there is room for improvement here).

The Microsoft Visual C++ source code and project for AllPlays.dll is
included.

---------------

The iPod tool comes in the form of a standalone Java application.  First
edit AllPlays.bat to insert the correct path.  To use AllPlays.bat:

  1. Close the iTunes application
  2. Plug in iPod
  3. Execute AllPlays.bat
  4. Press the "XML Plays" button (this updates the XML file)
  5. Start iTunes application

The key is that iTunes MUST be closed before plugging in the iPod,
otherwise it will grab the play-count information out of the iPod and 
delete it before AllPlays gets a chance to see it.

On first execution of AllPlays.bat, Preferences->Options must be set.
"iPod" and "AllPlays" are the only sections that need to be filled out.
The rest can be ignored.  It's recommended to write iPod plays to a 
different XML file than the one used for iTunes plays.

iPod tracks are counted as "played" when the end of the track is reached,
just like within iTunes.  For tracks that are played multiple times on the
iPod between AllPlays.bat runs, the multiple plays will be counted, but
the timestamp will not be correct for the older plays.

The Java source code is included.

----------------


2. Database
================
The AllPlays XML files are then used as input to a SQL database.  The
current Framework used web-based MySQL/PHP running on a remote Linux
server, but since the interface between Play Tracking and Database is simple
XML, any other methods/toolsets could be used.

The first major step is to replicate the iTunes database in the SQL database.
This is done by reading 'iTunes Music Library.xml', which is created
automatically by iTunes.  Whenever music is added or removed from the iTunes
library, and Play Counts are to be added to the SQL database, this step 
should be run again to resynchronize the two databases.

When the databases are synchronized, then the data from the AllPlays XML
files can be inserted.

Files:
  - html/: provides a simple web-based front-end to the SQL, allowing the 
     user to browse a music collection and view the play count of any 
     song/album.
  - musicdb/: the main database-processing scripts.  A separate README.txt
    in this directory details the usage of each file.  If run on a publicly-
    accessible web server, this directory must be password-protected.
    - musicdb/chg/: A duplicate of 'html/', but with added features to allow
      quick modification of titles in the SQL database.  Useful when a typo
      is discovered and changed in a song/album title in the iTunes database.
  - images/: images for the web-based front-end.

-------------


3. Synchronization
==================
This is the least important component of the Framework, but is included for
completeness.  It is used to update the play counts in iTunes to match the
play counts in the SQL database.  The main reason they would go out-of-sync
is if AllPlays data from multiple iTunes libraries/computers was being
funneled into one SQL database.

musicdb/create_play_counts.php can be used to create an AllPlays-like XML
file from the SQL data, and then this file will be read in by ReplacePlays.js
to push the play counts back into iTunes (ReplacePlaysTest.js should be run
first to ensure it will work as expected).  Backing up the iTunes database
is recommended anyway. 

Written in JavaScript using Windows Script Hosting (WSH)